---
type: flow
title: Declined Payment Path
description: The unhappy branch of Order Placement — what happens when the provider declines the charge.
tags: [flow]
parent_flow: Order Placement
timestamp: {{DATE}}
---
<!-- ✂ docujoint template sample — replace with your own content, then delete this comment. -->
# Declined Payment Path

## Overview
Branch of [Order Placement](<Order Placement.md>) taken when the provider
declines. Deliberately conservative: no order row is ever created for a
declined charge (see [order-status](</Data/main/Enums/order-status.md>) q1).

## Map
The decline conversation, concept by concept — note the audit write to
[payment_attempts](</Data/main/Tables/payment_attempts.md>) even though no
order is created:

```mermaid
sequenceDiagram
  participant Buyer as Buyer
  participant CP as Checkout Page
  participant Pay as Payments Service
  participant S as Stripe
  participant PA as payment_attempts
  Buyer->>CP: submit payment
  CP->>Pay: charge (idempotent by cart)
  Pay->>S: payment intent
  S-->>Pay: decline + reason code
  Pay->>PA: record attempt, outcome declined
  Pay-->>CP: typed error, no order row
  CP-->>Buyer: keep cart, show retry with reason
```

## Steps
1. Provider returns a decline code to the [Payments Service](</Services/Payments Service.md>).
2. The service records the attempt and returns a typed error — no
   [orders](</Data/main/Tables/orders.md>) row is created.
3. The [Checkout Page](</Apps/Storefront/Pages/Checkout Page.md>) keeps the
   cart intact and shows a retry affordance with the decline reason.

## Features

## Scenarios

## Open questions

## Transitions
| To | When |
|----|------|
| [Order Placement](<Order Placement.md>) | The buyer retries with another card — a new charge attempt under a new idempotency key |
| No order | A hard decline (fraud code) or the buyer walks away — the attempt stays recorded, the cart is kept |